/*******************************************************************************
 * Copyright (c) 2010 Mikhail Garber.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the GNU Lesser Public License (LGPL)
 * which accompanies this distribution
 * 
 * Contributors:
 *     Mikhail Garber - initial API and implementation
 ******************************************************************************/
package plumber.coordinator;

import java.util.Date;
import java.util.List;

/**
 * this Interface defines how system clients communicate with a Coordinator
 * @author mgarber
 *
 */
public interface CoordinatorClient {

	/**
	 * submit new work to the system
	 * @param namespace - string identifying namespace to be used for this request
	 * @param context - initial data to be made available to the Flow
	 * @param flowName - the name of the Flow to execute
	 * @return unique (GUID) request id to identify this workflow submission
	 */
	public String submitWork(String namespace, String context, String flowName);
	
	/**
	 * submit new work to the system
	 * @param namespace - string identifying namespace to be used for this request
	 * @param context - initial data to be made available to the Flow
	 * @param flowName - the name of the Flow to execute
	 * @param scheduled Date when this request needs to be processed and executed
	 * @return unique (GUID) request id to identify this workflow submission
	 */
	public String submitWork(String namespace, String context, String flowName, Date scheduled);
	
	/**
	 * get execution history of a given flow execution
	 * @param requestId of this flow 
	 * @return list of Strings representing WorkItems for this Flow execution. Caller can use
	 * ContextConverter to make Java objects out of them
	 */
	public List<String> getHistory(String requestId);
	
	/**
	 * check if this workflow execution completed
	 * @param requestId of the Flow
	 * @return true or false
	 */
	public boolean checkComplete(String requestId);
	
	/**
	 * check if this workflow execution failed
	 * @param requestId of the Flow
	 * @return true or false
	 */
	public boolean checkFailed(String requestId);
	
	/**
	 * obtain result of the work Flow execution
	 * @param requestId of the Flow
	 * @return string representation of FlowContext object that has flown thru all the Steps
	 * or a null if workflow has not completed or already failed
	 */
	public String getResult(String requestId);
	
	/**
	 * obtain all WorkItems in this namespace
	 * @param namespace
	 * @param upto this number of items in the result
	 * @return list of String representations of WorkItems
	 */
	public List<String> getAll(String namespace, int upto);
	
	/**
	 * Suspend execution of a Flow
	 * precondition: last WorkItem in execution history represents a Step in a AVAILABLE state
	 * (typically this happens if work flow gets stuck in retrying some step)
	 * @param requestId of the flow
	 * @return true or false if action was successful
	 */
	public boolean suspend(String requestId);
	
	/**
	 * Resume execution of previously suspended Flow
	 * @param requestId
	 * @return true or false if action was successful
	 */
	public boolean resume(String requestId);
	
}
